The Atari Compendium

home *** CD-ROM | disk | FTP | other *** search

/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / langs / prolog68.zoo / prolog.68 / doc / readme < prev

Wrap

Text File | 1994-06-03 | 23.7 KB | 707 lines

------------------------------------------------------------------------------- /¯¯¯¯¯) /¯) /¯¯¯¯¯) /¯¯¯¯¯) / /¯) / / / / ____/ / /¯) / / (_/ / / / / / / (_/ / / ____/ /¯¯¯¯) /¯¯¯¯¯) / / /¯¯¯¯¯) /¯¯¯¯¯) /¯¯¯) / ¯¯¯) / / / / / /¯¯¯ / /¯) / / / / /¯) / / /¯) / (___/ / /¯) / / /¯) / / / / / / (_/ / / / / (_/ / / (_/ / / (_/ / / (_/ / (_/ (_/ (_____/ (_/ (_____/ (___ / (_____/ (_____/ / / /¯¯¯¯ / (_____/ (pre-release version) © Copyright 1989-1994 Jens Kilian All rights reserved ------- Shipping list --------------------------------------------------------- CODES Pre-compiled versions of the compiler BUILTINS.WAM and run-time system DEBUGGER.WAM DRIVER.WAM DSTRUCT.WAM ENCODER.WAM INDEXER.WAM LIBRARY.WAM SHELL.WAM TMPALLOC.WAM XLATOR.WAM DOC LIESMICH This document (German version) README This document (English version) INIT.WAM Bootstrap information PROLOG.LST WAM.TOS Main program (emulator, primitive operations) MWAM.TOS Main program, MiNT library (untested!) ------- Overview -------------------------------------------------------------- This package contains pre-release version 0.94.17 of Prolog-68, a not entirely new :-) Prolog system for Atari's ST series. When the program is finished, it will be made publicly available as free software (NOT public domain software!) together with the source code. This will take some time yet. The present version may be freely distributed, but NOT modified or used commercially. 'Commercial use' includes distribution, if a fee is charged and if the rate for a single disk exceeds the sum of the disk's price and the postal (or other carrier's) charge by more than DM 2,- (at a reasonable rate of exchange, if applicable). Again: This is a pre-release version, meaning that I don't even guarantee the correctness of this document! Prolog-68 is based on the `Warren Abstract Machine'; it contains a compiler (written in Prolog) which translates program clauses into intermediate code. This intermediate code is stored (as direct threaded code) and executed by a simulator. The system attains a speed of 12 kLIPS on the 'nrev' Benchmark, which is quite acceptable on an Atari ST. The program was tested on an ST with 4MB of main storage, but should be able to run on all Atari computers with 680x0 processors. In case of problems with TTs, Falcons or accelerated STs, please supply accurate error reports; I can't make tests myself because I don't have access to that kind of hardware. As usual, `more is better' regarding main memory; at least 250 KB are required just to load the system. The files in the 'CODES' folder contain a pre-translated version of the compiler and user interface. DON'T MODIFY THESE FILES UNDER ANY CIRCUMSTANCES, OTHERWISE YOU WON'T BE ABLE TO START PROLOG-68! ------- Incompatibilities to previous versions -------------------------------- Version 0.9 to version 0.91: - On the Prolog level all characters are represented according to the Unicode standard (ISO DIS 10646-1.2 Basic Multilingual Plane). Previous versions used extended ASCII according to ISO 8859-1 resp. (still earlier) the Atari character set. The most important difference is in the representation of line endings in text files. All line endings read in are represented by the Prolog character code 16'2028 (ASCII NL = 16'0a is treated as equivalent on output). Programs that use is_endline/1 or is_newline/1 to test for line endings should encounter no difficulties; the same holds for using the "\n" escape sequence. (I will remove this special case in the next version because it gave me more problems than benefits. Sorry.) - According to the upcoming ISO standard, a 'cut' in the precondition of a call to '->'/2 has no effect on the rest of the clause. - The predicates constant/1 and nonconstant/1 have disappeared (replace them by atomic/1 resp. nonatomic/1). You don't want to know about this. Version 0.91 to version 0.93: - Line endings are represented by ASCII newlines again, for the reasons mentioned above. - The stream opening modes 'read_binary', 'write_binary' and 'append_binary' are no longer valid, since their purpose is served by the 'stream options' concept from the ISO standard. - It is no longer possible to list or trace compiled predicates. Access to single clauses is only possible for interpreted (dynamic) predicates. It is however still possible to set 'spy points' on compiled predicates in the debugger. - The debugger can now be explicitly switched on and off. It is no longer necessary to indicate the predicate to be debugged. The predicates debug/1 and trace/1 don't exist any more. Version 0.93 to version 0.94: - absolute_file_name/2 may have different results because it now supports '/' as a directory separator (e.g., when running MiNT). ------- Known bugs ------------------------------------------------------------ The present version 0.94.17 contains the following bugs (to be fixed in later versions): * NUL characters (ASCII 0) are not allowed in atoms' names. * Some database operations may not have correct update semantics. (I.e., a change may be visible to calls that were started before the change occurred.) ------- Invocation ------------------------------------------------------------ The following are legal command-line options: -help Prints a short description of all the options. -debug Switches on an internal debugging mode. As it stands, this will be of use to the author only. -dribble <file> Opens a file into which all characters read from the keyboard will be echoed (useful for reporting bugs). -code <size> Allocates memory to the code area; this holds all long-lived data structures (such as atoms, functors and clauses). -global <size> Allocates memory to the global area, holding all terms created during program execution. -local <size> Allocates memory to the local area (used to control program execution and to hold local variables). -reserve <size> Returns memory to the operating system. Prolog-68 stores all data in three big areas of memory. Their sizes are computed at start-up and never changed afterwards. This restriction may cause a Prolog program to abort for lack of memory, even though enough free memory is present (future versions will include a mechanism for redistributing free memory at run-time). On computers having little main memory, it is thus important to set reasonable sizes for the different areas. If no options are given to it, Prolog-68 uses a very coarse partitioning which works well only with large amounts of memory. On STs with only 1MB of RAM, at least the code area should be explicitly set to about 250-300 KB. If memory is even smaller, 150 KB will be the absolute minimum. To distribute available memory to the various areas, the options '-code', '-global', '-local' and '-reserve' can be used. These may occur in any order and may be repeated (in which case their values will accumulate). Each of these four options must be followded by an additional argument giving the amount of memory to allocate. This should be a decimal integer optionally followed by one of the characters 'k', 'K', 'm', 'M' or '%'. If one of the letters is given or the flag character is omitted, the indicated number of bytes (resp. KBytes or MBytes) is allocated; if '%' is given, the indicated percentage of not-yet-allocated memory is used. Contiguous percentages refer to the same total amount. If the command line doesn't include sizes for one or more of the three areas, the total amount of memory which remains free after parsing of the command line is distributed to the missing areas, using a ratio of 1:2:4 for the code, local and global area, respectively. As mentioned above, this partitioning is not suitable for small-memory systems; for these, at least the code area has to be enlarged. If some memory remains free after the partitioning, it will be returned to the operating system. This is especially important if other programs must be run (either started from Prolog-68, or in a multi-tasking environment like MiNT). The '-reserve' option can be used to explicitly return a given amount of memory; it must be followed by an argument in the format given above. The following examples assume that exactly 2 MByte of main memory are free at start-up: -code 1M -global 50% -local 25% 1 MByte is assigned to the code area. Of the remaining memory, half (512 KByte) is given to the global area, a quarter (256 KByte) to the local area. The remaining 256 KByte are returned to the operating system. -code 25% -local 512K -code 25% A quarter of the initial 2 MByte is assigned to the code area. Another 512 KByte go to the local area. Of the remaining 1 MByte, another quarter is given to the code area. The rest is assigned to the global area, since it has not been given a size. No options given (default) 1/7 of total memory is assigned to the code area, 2/7 to the local area. The remaining 4/7 go to the global area. No memory is returned to the operating system. ------- Predefined predicates ------------------------------------------------- I'm trying to create a complete Prolog system which is compatible to the upcoming ISO standard. The current version was inspired mostly by Edinburgh Prolog and dialects derived from it, so many details are likely to change. Most predefined predicates have already been implemented, but here they can only be described in short: - Control: ','/2 (the usual control constructs) ';'/2 '!'/2 '->'/2 call/1 '\+'/1 (non-provability, not a true negation) once/1 true/0 otherwise/0 (= true/0) fail/0 false/0 (= fail/0) repeat/0 if_exception/3 (error handling) signal_exception/1 signal_error/3 propagate_error/4 trap/2 set_error_handler/3 The 'cut' works inside metacalls, but its scope is limited. In 'call(X)', a 'cut' inside 'X' will have effect only inside the parentheses. A rule of thumb: `letters block the cut'. '->'/2 resembles a 'cut' which is restricted to part of a clause. The call (P -> Q; R) can be used as an IF/THEN/ELSE statement: If P can be satisfied, Q is called, otherwise R is called. (P -> Q) on its own is identical to (P -> Q; fail). The ISO standard requires a 'cut' within the precondition (P in the example) not to have an effect on the rest of the clause. Thus, the above rule does NOT apply here! if_exception/3 and signal_exception/1 will be replaced by their ISO equivalents (catch/3 and throw/1) in a future version. The predicates signal_error/3, propagate_error/4, trap/2 and set_error_handler/3 will by replaced by an ISO compatible error handling mechanism. - Input/Output: read/1 (input/output of terms) write/1 writeq/1 display/1 (always outputs to 'user'!) write_canonical/1 (output in prefix form, also called displayq/1) print/1 (output via portray/1, if defined by the user) portray_clause/1 (prints clauses in easy-to-read format) get0/1 (input/output of characters) get/1 skip/1 (*) put/1 (*) nl/0 tab/1 (* these predicates can take a parameter that is a full arithmetical expression) is_endfile/1 (specifies end-of-file character) is_newline/1 (specifies end-of-line character) is_newpage/1 (specifies end-of-page character) is_endline/1 (detects end-of-line - must be called with its argument fully instantiated!) open/4 (management of input/output streams) open/3 open_null_stream/1 close/1 current_stream/3 stream_property/2 nofileerrors/0 fileerrors/0 flush_output/1 set_input/1 set_output/1 current_input/1 current_output/1 absolute_file_name/2 read/2 (input/output of terms to arbitrary streams) write/2 writeq/2 display/2 write_canonical/2 (a.k.a. displayq/2) print/2 get0/2 (input/output of characters to arbitrary streams) get/2 skip/2 (*) put/2 (*) nl/1 tab/2 (* see above) character_count/2 (inquiry about streams' status) line_count/2 line_position/2 stream_position/2 set_stream_position/2 stream_position/3 see/1 (Prolog-10 compatible file handling) seeing/1 seen/0 tell/1 telling/1 told/0 ttyget0/1 (Prolog-10 compatible terminal input/output) ttyget/1 ttyskip/1 ttyput/1 ttynl/0 ttytab/1 op/3 (define or delete operators) current_op/3 (inquire current operators) sread/2 (read a term with its symbol table) sread/3 (the same, using an arbitrary input stream) An (input or output) stream is a special object that can be created using a call like open(+FileName, +Mode, -Stream) or open(+FileName, +Mode, -Stream, +Options). `FileName' is the name of a file, `Mode' must be one of the atoms 'read', 'write' or 'append'. `Options' if given must be a list of options from the following set, indicating that some defaults should be changed: type(Type) The type of the data contained in the stream: either 'text' (Atari text format), 'utf' (text that can contain non-Atari characters), or 'binary' (raw bytes). alias(Alias) An alias name for the stream (`Alias' must be an atom). eof_action(Action) What to do if an attempt is made to read past the end of a file; either 'error' (cause an error to occur), 'eof_code' (return the EOF indicator) or 'reset' (start over). reposition Present for compatibility only - in Prolog-68, all files opened by the user can be positioned. The stream returned by open/[3,4] can be used with e.g. write(+Stream, ?Term) and closed with close(+Stream). Besides file streams there are certain predefined streams, accessible through the following names: user (for compatibility) user_input user_output user_error - Arithmetic 'is'/2 (evaluate expressions) '=:='/2 (compare expressions) '=\='/2 '<'/2 '=<'/2 '>'/2 '>='/2 - Term classification: var/1 nonvar/1 atom/1 integer/1 atomic/1 nonatomic/1 (negation of atomic/1) composite/1 (composite term?) simple/1 (negation of composite/1) callable/1 (can term be called?) - Structure access: functor/3 arg/3 '=..'/2 name/2 (conversion between constants and strings) atom_chars/2 number_chars/2 numbervars/3 (enumerate variables in a term, e.g., for write/1) - Comparison of arbitrary terms: '=='/2 '\=='/2 '@<'/2 '@=<'/2 '@>'/2 '@>='/2 compare/3 sort/2 msort/2 keysort/2 When comparing terms with '@<', ..., '@>=', the following total ordering relation over the set of all terms is used: a) Variables @< Numbers @< Atoms @< Composite Terms b) Variable1 @< Variable2 is uniquely defined, but has no further meaning to the user c) Number1 @< Number2 iff Number1 < Number2 d) Atom1 @< Atom2 iff Atom1's name is lexicographically less than Atom2's name e) Term1 @< Term2 iff i) Term1's arity is less than Term2's arity ii) both arities are equal and functor(Term1) @< functor(Term2) iii) both arities and both functors are equal and there exists an i such that for all j, 1 ≤ j < i: argument(Term1, j) == argument(Term2, j) and argument(Term1, i) @< argument(Term2, i) compare/3 acts as if it were defined as compare('<', X, Y) :- X @< Y. compare('=', X, Y) :- X == Y. compare('>', X, Y) :- X @> Y. sort/2, msort/2 and keysort/2 sort lists according to the ordering relation explained above. sort/2 discards duplicate elements, msort/2 doesn't; keysort/2 expects a list of terms having the form Key - Value It ignores the 'Values' and uses the 'Keys' to sort the list. keysort/2 keeps duplicate elements and preserves their original ordering; for example, | ?- keysort([4-a, 1-b, 5-c, 1-d, 4-e, 0-f], Sorted). Sorted = [0-f, 1-b, 1-d, 4-a, 4-e, 5-c] These predicates are at best linear, in the worst case they are O(NlogN) (so we can safely conclude that they DON'T use 'quicksort'). - Program loading: compile/1 (all predicates not declared dynamic are compiled) consult/1 (just load, do not compile any predicates) reconsult/1 (same as consult/1, present for compatibility) The following ISO-style directives are recognized (others will be implemented in future versions): :-dynamic ... (declare a predicate to be dynamic) :-discontiguous ... (not needed in Prolog-68) :-include ... (include a file) - Program status: listing/0 (list all dynamic predicates) listing/1 (list some dynamic predicates) current_atom/1 (inquire known atoms etc.) current_predicate/2 predicate_property/2 halt/0 (halt the program) halt/1 (ditto, specifying the exit code) break (start a new run level) abort (abort and return to Prolog top level) - Debugger: trace/0 (start debugger in creep mode) debug/0 (start debugger in leap mode) nodebug/0 (stop debugger) spy/1 (set & delete spy (=break) points) nospy/1 leash/1 harness/1 debugging/1 unknown/2 (trap calls to undefined predicates) unknown(-OldAction, +NewAction) is an abbreviation for prolog_flag(unknown, -OldAction, +NewAction) (which see). For more detailed informations concerning debugging, consult any decent Prolog textbook. - Database operations: abolish/1 (completely delete predicates) abolish/2 asserta/1 (add clauses to a dynamic predicate) assertz/1 assert/1 (= asserta/1) retract/1 (delete clauses of a dynamic predicate) retractall/1 clause/2 (access clauses of a dynamic predicate) - Database references: Database references allow faster access to stored clauses, terms etc. asserta/2 (as above, also returning a database reference) assertz/2 assert/2 clause/3 instance/2 (given a reference, retrieve a clause or term) erase/1 (given a reference, delete a clause or term) - Internal database: The internal database exists for reasons of efficiency. It can only be used for storing terms, not for storing clauses. recorda/3 recordz/3 recorded/3 current_key/2 Using recorda(+Key, +Term, -Ref) resp. recordz(+Key, +Term, -Ref), the `Term' is stored in the internal database under `Key'. A database reference to the stored term is returned in `Ref'; it can be used to remove the term via erase/1. recorded(+Key, ?Term, ?Ref) retrieves a stored term, current_key(?KeyName, ?KeyTerm) inquires all known keys. - Set operations: setof/3 and bagof/3 have not been implemented yet. findall/3 (find all solutions of a goal) The difference between findall/3 and bagof/3 is the treatment of free variables in the goal passed as parameter. bagof/3 collects all solutions that yield the same values for these variables, while findall/3 regards all free variables as existentially quantified. - Grammar rules: expand_term/2 (Called before a clause is compiled; does transformation of grammar rules. The user can define the predicate term_expansion/2 to make additional transformations.) phrase/3 (application of a grammar rule) phrase/2 phrase/[2,3] can handle an entire phrase (right-hand side of a grammar rule). phrase/2 is defined as phrase(Phrase, List) :- phrase(Phrase, List, []). - Miscellaneous: '='/2 (unification) length/2 (list operations) member/2 memberchk/2 append/3 prolog_flag/3 (inquire/modify global flags) prolog_flag/2 prompt/2 (inquire/modify console input prompt) statistics/0 (print statistics) statistics/2 (inquire statistics) garbage_collect/0 (force garbage collection) system/1 (pass an atom to a shell, e.g., Guläm) prolog_flag/2 and prolog_flag/3 access some global flags which are used to control several internal features. Contrary to other Prolog systems, the value of a flag is always an integer (but this may change in future versions). The currently existing flags are: Name Values (Default) Purpose character_escapes 0, 1 (0) Controls evaluation of escape sequences on input and output fileerrors 0, 1 (1) Controls error handling when accessing nonexistent files gc_trace 0, 1, 2 (0) Controls amount of tracing information printed when the garbage collector is run (0=none, 1=terse, 2=verbose) unknown 0, 1 (1) Controls handling of undefined predicates (0=just fail, 1=signal an error) error_handling 0, 1, 2 (2) Controls error handling (0=failure, 1=activation of error handling routine, 2=additional error messages) prolog_flag(+Flag, -OldValue, +NewValue) can be used to change the value of the `Flag', prolog_flag(?Flag, ?Value) inquires such a value without changing it. The first parameter to statistics/2 must be one of the following keywords: 'runtime' inquire the running time 'memory' inquire the sizes of various memory areas 'core' (some are duplicates, e.g., heap = program) 'program' 'heap' 'global_stack' 'local_stack' 'trail' 'garbage_collection' garbage collection statistics (what else?) The second parameter is unified with a list of integers indicating the results of the inquiry. I know that this list is no sufficient documentation, but unfortunately I can't supply more at this time. At least I'm working on a manual written in LaTeX. ------- Miscellany ------------------------------------------------------------ Addresses: German Federal Snail: Jens Kilian Holunderstraße 19 D-71083 Herrenberg Germany Internet: jensk@hpbbn.bbn.hp.com MausNet: Jens Kilian @ BB There are unreasonable people out there, so I must specifically disclaim any warranty even for this pre-release version: NO WARRANTY - BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. - IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. My employers haven't even heard of Prolog-68, so don't waste effort on them. ------------------------------------------------------------------------------- Have fun, Jens Kilian